home *** CD-ROM | disk | FTP | other *** search
/ Atari Mega Archive 1 / Atari Mega Archive - Volume 1.iso / gnu / gawk / cawf2st.zoo / cawf.man < prev    next >
Text File  |  1991-06-04  |  11KB  |  261 lines
  1.  
  2.  
  3. CAWF(1)                    Unix Programmer's Manual                    CAWF(1)
  4.  
  5.  
  6. NAME
  7.      cawf - C version of the nroff-like, Amazingly Workable (text) Formatter
  8.  
  9. SYNOPSIS
  10.      cawf [ -fb|e|i ] [ -macros ] [ file ... ]
  11.  
  12. DESCRIPTION
  13.      Cawf formats the text from the input file(s) (standard input if none)  in
  14.      an  approximation  of nroff.  It comes closest to duplicating nroff's man
  15.      or ms macro package styles.
  16.  
  17. OPTIONS
  18.      Options must precede file names.
  19.  
  20.      -fb  specifies that backspace and underline sequences are to be  used  to
  21.           emulate bold and italic characters.  This is cawf's default mode.
  22.  
  23.      -fe  specifies that ESC, followed by `B' is to be used  to  precede  each
  24.           bold character; and ESC, followed by `I', each italic character.
  25.  
  26.           This option is normally used with a post-filter  that  converts  the
  27.           ESC sequences into device-specific controls - e. g., fontfilt(1).
  28.  
  29.      -fn  specifies that no special character sequences  are  to  be  used  to
  30.           represent bold or italic characters.
  31.  
  32.      -macro
  33.           specifies the macro file to be used.  The standard cawf distribution
  34.           supplies macro files to support `-man' or `-ms'.  Cawf finds a macro
  35.           file by constructing its name from `m', acro and .mac - e. g.,  -man
  36.           is  converted  to man.mac.  The default directory for macro files is
  37.           defined when cawf is compiled;  it's  c:\sys\lib\cawf  in  the  cawf
  38.           MS-DOS distribution.
  39.  
  40.      file ...
  41.           are the names of files containing nroff source text.
  42.  
  43. NROFF COMPATIBILITY
  44.      Cawf accepts the following raw nroff requests:
  45.  
  46.           .\"  .ad  .bp  .br  .ce  .de  .di  .ds
  47.           .el  .fi  .ft  .i0  .ie  .if  .in  .it
  48.           .lg  .li  .ll  .ls  .na  .ne  .nf  .nr
  49.           .ns  .pl  .po  .ps  .rm  .rr  .rs  .so
  50.           .sp  .ta  .ti  .tm  .tr
  51.  
  52.      and the following in-text codes:
  53.  
  54.           \$   \%   \*   \c   \f   \h   \k   \n   \s   \w
  55.  
  56.      plus the full list of nroff/troff special characters in the  original  V7
  57.      troff manual.
  58.  
  59.      Many restrictions are present; the behavior in general  is  a  subset  of
  60.      nroff's.  Of particular note are the following:
  61.  
  62.  
  63.  
  64. Purdue University                       February, 1991                       1
  65.  
  66.  
  67.  
  68. CAWF(1)                    Unix Programmer's Manual                    CAWF(1)
  69.  
  70.  
  71.      +✓o Point sizes do not exist; .ps is ignored.
  72.  
  73.      +✓o Special vertical spacing - the .vs command included - is ignored.
  74.  
  75.      +✓o Conditionals cover only numeric comparisons on  \n(.$,  string  compar-
  76.        isons  between a macro parameter and a literal, and n (always true) and
  77.        t (always false).
  78.  
  79.      +✓o The handling of strings is generally primitive.
  80.  
  81.      +✓o Horizontal motion via \h  must  be  supplied  with  a  number  register
  82.        interpolation and must be positive - e. g., \w\n(NN, where the value in
  83.        NN is >= 0.
  84.  
  85.      +✓o The \k function is reliable only after TAB characters, so it is  useful
  86.        only for measuring table positions.
  87.  
  88.      +✓o The .di command only turns output on  and  off  -  any  macro  name  is
  89.        ignored.
  90.  
  91.      +✓o Expressions - e. g., .sp - are reasonably general, but the |, &, and  :
  92.        operators  do  not  exist, there must be white space between the end of
  93.        the nroff command and the beginning of the expression, and \w  requires
  94.        that  quote  (')  be  used as the delimiters.  \w counts the characters
  95.        inside the quotes and scales the result in ens, so that,  for  example,
  96.        \w'\(bu' equals 4n, and \w'\(bu'/1n equals 4.
  97.  
  98.      +✓o The only acceptable count for  the  .it  command  is  one,  and  it  is
  99.        effective only with man or ms macros.
  100.  
  101.      +✓o The default scaling factor is `v' for the .ne, .sp, and .pl  raw  nroff
  102.        requests;  it  is  `u' for .nr; and `n' for .in, .ll, .ls, .po, .ta and
  103.        .ti.  (A different scaling factor may  be  specified  with  a  trailing
  104.        character.)
  105.  
  106.      +✓o Some obsolete or meaningless commands - .i0, .lg and .li - are silently
  107.        ignored.
  108.  
  109.      White space at the beginning of lines, and embedded  white  space  within
  110.      lines  is dealt with properly.  Sentence terminators at ends of lines are
  111.      understood to imply extra space afterward in filled lines.  Tabs are  im-
  112.      plemented  crudely  and  not  exactly,  although  usually  they  work  as
  113.      expected.  Hyphenation is done only at explicit hyphens,  em-dashes,  and
  114.      nroff  discretionary  hyphens.   Bolding  and italicization are done with
  115.      backspacing and overprinting.
  116.  
  117. MAN MACROS
  118.      The man macro set replicates the full V7 manual macros, plus a few  semi-
  119.      random oddballs.  The full list is:
  120.  
  121.           .AT  .B   .BI  .BR  .BY  .DE  .DS  .DT  .HP  .I
  122.           .IB  .IP  .IR  .IX  .LP  .NB  .P   .PD  .PP  .RB
  123.           .RE  .RI  .RS  .SH  .SM  .TH  .TP  .UC
  124.  
  125.  
  126.  
  127.  
  128.  
  129. Purdue University                       February, 1991                       2
  130.  
  131.  
  132.  
  133. CAWF(1)                    Unix Programmer's Manual                    CAWF(1)
  134.  
  135.  
  136.      .BY and .NB each take a single string argument  (respectively,  an  indi-
  137.      cation  of authorship and a note about the status of the manual page) and
  138.      arrange to place it in the page footer.  .AT and .IX do nothing.
  139.  
  140. MS MACROS
  141.      The ms macro set is a substantial subset of  the  V7  manuscript  macros.
  142.      The macros are:
  143.  
  144.           .AB  .AE  .AI  .AU  .B   .CD  .DA  .DE  .DS  .I
  145.           .ID  .IP  .LD  .LG  .LP  .ND  .NH  .NL  .PP  .QE
  146.           .QP  .QS  .R   .RE  .RP  .RS  .SH  .SM  .TL  .TP
  147.           .UL  .UX
  148.  
  149.      Size changes are recognized but ignored, as are .RP and  .ND.   .UL  just
  150.      prints  its  argument in italics.  .DS/.DE does not do a keep, nor do any
  151.      of the other macros that normally imply keeps.
  152.  
  153.      The DY string variable is available.  The PD, PI, and LL number registers
  154.      exist and can be changed.
  155.  
  156. HEADERS AND FOOTERS
  157.      Cawf allows the placement of text into the five line  header  and  footer
  158.      sections  from  the  LH, CH, RF, LF, CF, and RF string variables, via the
  159.      control of the .^b command:
  160.  
  161.      .^b fh 1   enables header string placement on the first page
  162.      .^b fh 0   disables header string placement on the first page
  163.      .^b HF 1   enables header/footer string placement
  164.      .^b HF 0   disables header/footer string placement
  165.  
  166.      There are appropriate .^b commands in the distribution man and  ms  macro
  167.      files.   (The  ms  macro file uses another .^b command, .^b NH, to enable
  168.      numbered header processing.)
  169.  
  170. OUTPUT
  171.      The default output format supported by cawf, in its distributed form,  is
  172.      that  appropriate to a dumb terminal, using overprinting for italics (via
  173.      underlining) and bold.  The nroff special characters are printed as  some
  174.      vague  approximation  (it's  sometimes  extremely vague) to their correct
  175.      appearance.
  176.  
  177.      Cawf's knowledge of the output device is established by  a  device  file,
  178.      which  is  read  before  the  user's  input.  The search for it begins in
  179.      cawf's library directory, under the name  term.dev  (where  term  is  the
  180.      value  of  the  TERM  environment  variable).  Failing to find that, cawf
  181.      searches for dumb.dev.  The device file uses special internal commands to
  182.      set up resolution, special characters, fonts, etc., and more normal nroff
  183.      commands to set up page length, etc.
  184.  
  185.      Cawf has limited support for special forms of bold and italic characters.
  186.      It  is  provided  through  the  -fe  option  and  post-filters  -  e. g.,
  187.      fontfilt(1).  The -fe option causes cawf to precede each  bold  character
  188.      with  ESC  and  `B';  each  italic  character, ESC and `I'.  The fontfilt
  189.      post-filter converts  these  escape  sequences  into  appropriate  device
  190.      control codes.  (Fontfilt will also select a font (once).)
  191.  
  192.  
  193.  
  194. Purdue University                       February, 1991                       3
  195.  
  196.  
  197.  
  198. CAWF(1)